<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Progress Bar Examples - Ratings</title>
<!-- css -->
<link rel="stylesheet" type="text/css" href="../../build/reset-fonts-grids/reset-fonts-grids.css">
<link rel="stylesheet" type="text/css" href="../../build/base/base.css">
<link rel="stylesheet" type="text/css" href="../../build/progressbar/assets/skins/sam/progressbar.css">
<link rel="stylesheet" type="text/css" href="../../build/datatable/assets/skins/sam/datatable.css">


<link rel="stylesheet" type="text/css" href="http://developer.yahoo.com/yui/assets/dpSyntaxHighlighter.css">

<!-- js -->
<script type="text/javascript" src="../../build/yahoo-dom-event/yahoo-dom-event.js"></script>
<script type="text/javascript" src="../../build/animation/animation-min.js"></script>
<script type="text/javascript" src="../../build/element/element-min.js"></script>

<script type="text/javascript" src="../../build/get/get-min.js"></script>
<script type="text/javascript" src="../../build/datasource/datasource-min.js"></script>
<script type="text/javascript" src="YQLDataSource.js"></script>
<script type="text/javascript" src="../../build/datatable/datatable-min.js"></script>

<script type="text/javascript" src="../../build/progressbar/progressbar-debug.js"></script>


<style type="text/css">

.yui-skin-sam .ratings {
	background:white none repeat 0 0;
}
.yui-skin-sam .ratings .yui-pb-bar  {
	background: transparent url(star.png) repeat-x 0 0;
}

/* Just a little decoration for the page, not relevant to the usage of the progress bar */

code {
	background-color:#e0e0e0;
	border:thin solid #c0c0c0;
	white-space:pre;
	font-size:10px;
}

.dp-highlighter th, .dp-highlighter td {
	border:0;
	padding:0;
}
.dp-highlighter .line1, .dp-highlighter  .line2 {
	padding-left:10px;
	white-space:nowrap;
}

</style>
</head>
<body class="yui-skin-sam">
	<div id="doc">
		<div id="hd">
			<h1>Progress Bar Examples - Ratings</h1>
			<p>The ProgressBar can be used within other widgets.   
			Here we are using Yahoo! Query Language, <a href="http://developer.yahoo.com/yql/">YQL</a> 
			looking for Sushi restaurants in San Francisco, CA. and displaying the information in a 
			<a href="http://developer.yahoo.com/yui/datatable/">YUI DataTable</a>.  
			We are showing some of the plain text fields as such, but for the ratings of the restaurants
			we are using the ProgressBar.</p>
		</div>
		<div id="bd">
			<div id="Container"></div>
		</div>
		<div id="ft">
			<p>The Ratings from the query are being represented by YUI ProgressBars.</p>
			<p>YQL allows to query some of YAHOO! vast databases using a language similar to SQL. 
			The query for this examples is:</p>
			<textarea name="code" class="JScript" cols="60" rows="1">
				select Title,Address,Phone, Rating.AverageRating from local.search 
					where query="sushi" and location="san francisco, ca"
			</textarea>
			<p>which can be tested by pasting it into the <a href="http://developer.yahoo.com/yql/console/">YQL Console</a>. 
			YQL replies directly to an HTTP request with the search results either in 
			<a href="http://query.yahooapis.com/v1/public/yql?q=select%20*%20from%20local.search%20where%20query%3D%22sushi%22%20and%20location%3D%22san%20francisco%2C%20ca%22&format=xml">XML</a> 
			or <a href="http://query.yahooapis.com/v1/public/yql?q=select%20*%20from%20local.search%20where%20query%3D%22sushi%22%20and%20location%3D%22san%20francisco%2C%20ca%22&format=json&callback=cbfunc">JSON</a> format,
			this last being suitable to be used with the <a href="http://developer.yahoo.com/yui/get/">YUI Get utility</a>.
			However, we are using a freely available subclass of <a href="http://developer.yahoo.com/yui/datasource/">YUI DataSource</a> which handles
			the communication with YQL for us.</p>
			<p>The code to build the DataTable on that query is:</p>
			<textarea name="code" class="JScript" cols="60" rows="1">
				var dt = new YAHOO.widget.DataTable(
					'Container',
					[
						{key:"Title", sortable:true},
						{key:"Address", sortable:true},
						{key:"Phone", sortable:true},
						{key:"Rating.AverageRating", label:"Rating", formatter:ratingFormatter,	sortable:true}
					],
					new YAHOO.util.YQLDataSource(),
					{
						initialRequest:'select Title, Address, Phone, Rating.AverageRating from local.search where query="sushi" and location="san francisco, ca"'
					}
				);
			</textarea>
			<p>We are drawing a simple DataTable with four columns, the first three of them, Title, Address and Phone are simple
			text fields that are displayed just as they are received.  The fourth field is the one we are interested in.
			The query returns that field nested within the structure of each record.  The property <code>Rating</code> is actually 
			an object which contains several other properties and from those we choose <code>AverageRating</code>, thus, we
			use the composite field name <code>Rating.AverageRating</code> both in the query and in the <code>key</code> for the
			column definitions.  Since that is not an acceptable label for the column header, we have to provide one and 
			assign it a custom formatter. All columns are sortable, even the Ratings column.</p>

			<p>The <code>ratingFormatter</code> is the one that will draw the ProgressBars:<p>
			<textarea name="code" class="JScript" cols="60" rows="1">
				var pbs = [];
				var ratingFormatter = function (elLiner, oRecord, oColumn, oData) {
					var pb = new YAHOO.widget.ProgressBar({
						width:'100px', 
						height:'20px', 
						maxValue:5, 
						className:'ratings',
						value:YAHOO.util.DataSource.parseNumber(oData)
					}).render(elLiner);
					pbs.push(pb);
				};
			</textarea>
			<p>The core of it is the creation of the ProgressBar 100px wide and 20px hight because our star is in a square 20pixels on each side so that
			up to five stars will fit horizontally.  Five is, indeed, the <code>maxValue</code> that the rating 
			might reach.  We add a className <code>"rating"</code> to the widget, which will help us with some formatting details
			and, finally, we set the current value for the progressBar to the new value for the cell, after converting it to a number.
			Unfortunately, YQL returns everything as strings.</p>
			
			<p>Everytime the DataTable is sorted or redrawn for any reason, such as call to the <code>render</code> method or paging, 
			the formatters will be called again.  As with any widget, the ProgressBar might take resources that might not be
			automatically cleared by the garbage collector.  It is vital to call method <code>destroy</code> to make sure all such
			resources are cleared.  We push the ProgressBar instances created into the array <code>pbs</code>.  To destroy
			those instances, we do:</p>
			<textarea name="code" class="JScript" cols="60" rows="1">
				dt.on('beforeRenderEvent',function() {
					for (var i = 0; i < pbs.length; i++) {
						pbs[i].destroy();
					}
					pbs = [];
				});
			</textarea>
			<p>Before any render, we make sure we destroy every instance we might have stored in the <code>pbs</code> array, 
			if any.</p>
			
			<p>The stars come from this single star <img src="star.png" /> which the ProgressBar tiles until it fills the allotted space.
			The style settings for this example is:</p>
			<textarea name="code" class="CSS" cols="60" rows="1">
				.yui-skin-sam .ratings {
					background:white none repeat 0 0; 
				}
				.yui-skin-sam .ratings .yui-pb-bar  {
					background: transparent url(star.png) repeat-x 0 0;
				}
			</textarea>
			<p>We are using <code>.yui-skin-sam .ratings</code> as a selector in all the styles.  
			We use the <code>yui-skin-sam</code> for basic skinning in all the page, including the DataTable, so we need to
			override some of its settings.  We gave the <code>ratings</code> className to all the ProgressBars
			as one of the arguments in their instantiation.  Since the star icon fades to white, we set the background to white.
			In the second definition, we set the background image for the bar itself to the star icon.  
			We leave the borders that the SAM skin provides.</p>
			
		</div>
	</div>
	
<script  type="text/javascript">

	YAHOO.util.Event.onDOMReady(function () {
		var pbs = [];
		var ratingFormatter = function (elLiner, oRecord, oColumn, oData) {
			var pb = new YAHOO.widget.ProgressBar({
				width:'100px', 
				height:'20px', 
				maxValue:5, 
				className:'ratings',
				value:YAHOO.util.DataSource.parseNumber(oData)
			}).render(elLiner);
			pbs.push(pb);
		};

		var dt = new YAHOO.widget.DataTable(
			'Container',
			[
				{key:"Title",sortable:true},
				{key:"Address",sortable:true},
				{key:"Phone",sortable:true},
				{key:"Rating.AverageRating",label:"Rating",	sortable:true, formatter:ratingFormatter}
			],
			new YAHOO.util.YQLDataSource(),
			{
				initialRequest:'select Title,Address,Phone, Rating.AverageRating from local.search where query="sushi" and location="san francisco, ca"'
			}
		);
		dt.on('beforeRenderEvent',function() {
			for (var i = 0; i < pbs.length; i++) {
				pbs[i].destroy();
			}
			pbs = [];
		});
	});
</script>
<script type="text/javascript" src="http://developer.yahoo.com/yui/assets/dpSyntaxHighlighter.js"></script>
<script type="text/javascript" language="javascript">dp.SyntaxHighlighter.HighlightAll('code');</script>
</body>
</html>
	
